Network CD 2

home *** CD-ROM | disk | FTP | other *** search

/ Network CD 2 / Network CD - Volume 2.iso / programs / internet / tcp / amitcp / amitcp-api-22.lha / AmiTCP-2.2 / doc / netlib.doc < prev next >

Wrap

Text File | 1993-10-21 | 25.8 KB | 777 lines

TABLE OF CONTENTS netlib.doc/autoinitd netlib.doc/autoinit netlib.doc/charRead netlib.doc/getgrgid netlib.doc/getgrnam netlib.doc/gethostname netlib.doc/getpwnam netlib.doc/getpwuid netlib.doc/gettimeofday netlib.doc/group netlib.doc/lineRead netlib.doc/passwd netlib.doc/timerinit netlib.doc/autoinitd netlib.doc/autoinitd NAME autoinitd - SAS C Autoinitialization Functions for Daemons SYNOPSIS void _STIopenSockets(void); void _STDcloseSockets(void); long server_socket; DESCRIPTION These are SASC autoinitialization functions for internet daemons started by inetd, Internet super-server. Upon startup, the server socket is obtained with ObtainSocket() library call. If successful, the socket id is stored to the global variable server_socket. If the socket is not obtainable, the server_socket contains value -1. Upon success, the server_socket contains value 0. If the server_socket is not valid, the server may try to accept() a new connection and act as a stand-alone server. RESULT server_socket - positive socket id for success or -1 for failure. NOTES _STIopenSockets() also checks that the system version is at least 37. It puts up a requester if the bsdsocket.library is not found or is of wrong version. The autoinitialization and autotermination functions are features specific to the SAS C6. However, these functions can be used with other (ANSI) C compilers, too. Example follows: /* at start of main() */ atexit(_STDcloseSockets); _STDopenSockets(); AUTHORS Jarno Rajahalme, Pekka Pessi, the AmiTCP/IP Group <amitcp-group@hut.fi>, Helsinki University of Technology, Finland. SEE ALSO serveraccept(), netutil/inetd netlib.doc/autoinit netlib.doc/autoinit NAME autoinit - SAS C Autoinitialization Functions SYNOPSIS _STIopenSockets() void _STIopenSockets(void) _STDcloseSockets() void _STDcloseSockets(void) FUNCTION These functions open and close the bsdsocket.library at the startup and exit of the program, respectively. For a program to use these functions, it must be linked with netlib:net.lib. If the library can be opened, the _STIopenSockets() calls bsdsocket.library function SetErrnoPtr() to tell the library the address and the size of the errno variable of the calling program. NOTES _STIopenSockets() also checks that the system version is at least 37. It puts up a requester if the bsdsocket.library is not found or is of wrong version. The autoinitialization and autotermination functions are features specific to the SAS C6. However, these functions can be used with other (ANSI) C compilers, too. Example follows: /* at start of main() */ atexit(_STDcloseSockets); _STDopenSockets(); BUGS SEE ALSO bsdsocket.library/SetErrnoPtr(), SAS/C 6 User's Guide p. 145 for details of autoinitialization and autotermination functions. netlib.doc/charRead netlib.doc/charRead NAME charRead -- read characters from socket one by one. SYNOPSIS initCharRead(rc, fd) void initCharRead(struct CharRead *, int); character = charRead(rc) int charRead(struct CharRead *); DESCRIPTION charRead is a macro package which return characters one by one from given socket input stream. The socket where data is to be read is set by calling initCharRead(): rc is the pointer to charread structure previously allocated. fd is the (socket) descriptor where reading is to be done. charRead() returns the next character from input stream or one of the following: RC_DO_SELECT (-3) - read input buffer is returned. Do select before next call if you don't want charread to block. RC_EOF (-2) - end-of-file condition has occurred. RC_ERROR (-1) - there has been an error while filling new charread buffer. Check the value of Errno() NOTE Always use variable of type int to store return value from charRead() since the numeric value of characters returned may vary between 0 -255 (or even greater). As you may know, -3 equals 253 if of type unsigned char. EXAMPLE /* * This piece of code shows how to use charread with select() */ #include <sys/types.h> #include <sys/socket.h> #include <charread.h> main_loop(int sock) { struct CharRead rc; fd_set readfds; int c; initCharRead(&rc, sock); FD_ZERO(&readfds); while(1) { FD_SET(sock, &readfds); if (select(sock + 1. &readfds, NULL, NULL, NULL)) < 0) { perror("select"); break; } if (FD_ISSET(sock, &readfds)) { while((c = charRead(&rc)) >= 0) handle_next_input_character(c); if (c == RC_EOF) break; if (c == RC_ERROR) { perror("charRead"); break; } } } } PORTABILITY The source file charread.h should be able to be used in UNIX programs as is. AUTHORS Tomi Ollila, the AmiTCP/IP Group <amitcp-group@hut.fi>, SEE ALSO lineRead(), bsdsocket.library/recv() netlib.doc/getgrgid netlib.doc/getgrgid SEE ALSO getgrnam() netlib.doc/getgrname netlib.doc/getgrnam NAME getgrnam, getgrgid - group database operations SYNOPSIS #include <grp.h> struct group * getgrname(const char *name) struct group * getgrgid(gid_t gid) DESCRIPTION These functions operate on the group database file AmiTCP:db/group which is described in netlib.doc/group. Each line of the database is defined by the structure group found in the include file <grp.h>: struct group { UBYTE *gr_name; /* Group name. */ UBYTE *gr_passwd; /* Password. */ ULONG gr_gid; /* Group ID. */ UBYTE **gr_mem; /* Member list. */ }; The functions getgrnam() and getgrgid() search the group database for the given group name pointed to by name or the group id pointed to by gid, respectively, returning the first one encountered. Identical group names or group gids may result in undefined behavior. RETURN VALUES The functions getgrent(), getgrnam(), and getgrgid(), return a pointer to the group entry if successful; if end-of-file is reached or an error occurs a null pointer is returned. The functions setgroupent() and setgrent() return the value 1 if successful, otherwise the value 0 is returned. The functions endgrent() and setgrfile() have no return value. FILES AmiTCP:db/group group database file SEE ALSO getpwnam(), group HISTORY The functions getgrnam() and getgrgid() appeared in Version 7 AT&T UNIX. BUGS The functions getgrnam() and getgrgid() leave their results in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object. COMPATIBILITY The BSD passwd database handling routines getgrent(), setgrfile(), endgrent(), setgroupent(), and setgrent() are fairly useless in a networked environment and they are not implemented. netlib.doc/gethostname netlib.doc/gethostname NAME gethostname -- get the name of the host SYNOPSIS error = gethostname(name, namelen); int gethostname(char *, int); FUNCTION Get the name of the host to the buffer name of length namelen. The name is taken from the environment variable "HOSTNAME" where it SHOULD reside. INPUTS name - Pointer to the buffer where the name should be stored. namelen - Length of the buffer name. RESULT error - 0 on success, -1 in case of an error. The global variable errno will be set to indicate the error as follows: ENOENT - The environment variable "HOSTNAME" is not found. EXAMPLE char hostname[MAXHOSTNAMELEN]; int error; error = gethostname(hostname, sizeof(hostname)); if (error < 0) exit(10); printf("My name is \"%s\".\n", hostname); NOTES This function is included for source compatibility with Unix systems. The ENOENT errno value is AmiTCP/IP addition. BUGS Unlike the Unix version, this version assures that the resulting string is always NULL-terminated. The hostname is fetched from environment variable, which may cause environment collisions. There is no sethostname(). SEE ALSO getenv() netlib.doc/getpwnam netlib.doc/getpwnam NAME getpwnam, getpwuid - password database operations SYNOPSIS #include <sys/types.h> #include <pwd.h> struct passwd * getpwnam(const char *login) struct passwd * getpwuid(uid_t uid) DESCRIPTION These functions operate on the password database file which is described in netlib.doc/passwd. Each entry in the database is defined by the structure passwd found in the include file <pwd.h>: struct passwd { UBYTE *pw_name; /* Username */ UBYTE *pw_passwd; /* Encrypted password */ ULONG pw_uid; /* User ID */ ULONG pw_gid; /* Group ID */ UBYTE *pw_gecos; /* Real name etc */ UBYTE *pw_dir; /* Home directory */ UBYTE *pw_shell; /* Shell */ }; The functions getpwnam() and getpwuid() search the password database for the given login name or user uid, respectively, always returning the first one encountered. RETURN VALUES The functions getpwnam() and getpwuid() return a valid pointer to a passwd structure on success and a null pointer if end-of-file is reached or an error occurs. FILES AmiTCP:db/passwd The password database file SEE ALSO getgrgid(), passwd HISTORY The getpwnam() and getpwuid() functions appeared in Version 7 AT&T UNIX. BUGS The functions getpwnam() and getpwuid() leave their results in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object. COMPATIBILITY The BSD passwd database handling routines getpwent(), setpwfile(), endpwent(), setpassent(), and setpwent() are fairly useless in a networked environment and they are not implemented. netlib.doc/getpwuid netlib.doc/getpwuid SEE ALSO getpwnam() netlib.doc/gettimeofday netlib.doc/gettimeofday NAME gettimeofday - get date and time SYNOPSIS #include <sys/time.h> error = gettimeofday(tp, tzp) int gettimeofday(struct timeval *, struct timezone *) FUNCTION The system's notion of the current Greenwich time and the current time zone is obtained with the gettimeofday() call. The time is expressed in seconds and microseconds since midnight (0 hour), January 1, 1970. The resolution of the system clock is hardware dependent. If tzp is zero, the time zone information will not be returned. Also, if your system software is unable to provide time zone information, the structure pointed by tzp will be filled with zeroes. PORTABILITY UNIX INPUTS The structures pointed to by tp and tzp are defined in <sys/time.h> as: struct timeval { long tv_sec; /* seconds since Jan. 1, 1970 */ long tv_usec; /* and microseconds */ }; struct timezone { int tz_minuteswest; /* of Greenwich */ int tz_dsttime; /* type of dst correction to apply */ }; The timezone structure indicates the local time zone (meas- ured in minutes of time westward from Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. RESULT Returns 0 when successful and -1 with specific error code in errno in case of an error. No error codes are specified, however. NOTES gettimeofday() uses GetSysTime() function of the timer.device, which is new to V36 of the device. Time zone information is available only if your system has locale.library, which is included in all Amiga systems from 2.1 and up. Global variable TimerBase _must_ be initialized before gettimeofday() is called. This is normally done automatically by the autoinit module (timerinit.c) included in the net.lib. BUGS The time zones are currently not supported. SEE ALSO timer.device/GetSysTime() netlib.doc/group netlib.doc/group NAME group - format of the group permissions file DESCRIPTION The file <AmiTCP:db/group> consists of newline separated ASCII records, one per group, containing four bar `|' separated fields. These fields are as follows: group Name of the group. passwd Group's encrypted password. gid The group's decimal ID. member Group members. The group field is the group name used for granting file access to users who are members of the group. The gid field is the number associated with the group name. They should both be unique across the system (and often across a group of systems) since they control file access. The passwd field is an optional encrypted password. This field is rarely used and an asterisk is normally placed in it rather than leaving it blank. The member field contains the names of users granted the priviledges of group. The member names are separated by commas with out spaces or newlines. A user is automatically in a group if that group was specified in their AmiTCP:db/passwd entry and does not need to be added to that group in the AmiTCP:db/group file. FILES AmiTCP:db/group SEE ALSO netlib/getgrgid(), netlib/getgrnam() BUGS Group information is not necessarily stored to local file. The library functions getgr*() are the preferred way to access the user database. COPYRIGHT Copyright 1980, 1991 The Regents of the University of California. HISTORY A group file format appeared in Version 6 AT&T UNIX. netlib.doc/lineRead netlib.doc/lineRead NAME lineRead -- read newline terminated strings from socket SYNOPSIS initLineRead(rl, fd, lftype, bufsize) void initLineRead(struct LineRead *, int, int, int); length = lineRead(rl) int lineread(struct LineRead *); DESCRIPTION lineRead() reads newline terminated strings from given descriptor very efficiently. All the options needed are set by calling initLineRead(): rl is the pointer to lineread structure previously allocated. fd is the (socket) descriptor where reading is to be done. lftype can have following 3 values: RL_LFNOTREQ - Newline terminated strings are returned unless there is no newlines left in currently buffered input. In this case remaining buffer is returned. RL_LFREQLF - If there is no newlines left in currently buffered input the remaining input data is copied at the start of buffer. Caller is informed that next call will fill the buffer (and it may block). Lines are always returned with newline at the end unless the string is longer than whole buffer. RL_LFREQNUL - Like LF_REQLF, but remaining newline is removed. Note here that lenght is one longer that actual string length since line that has only one newline at the end would return length as 0 which indigate string incomplete condition. bufsize is used to tell lineread how big the receive buffer is. always put RL_BUFSIZE here since that value is used to determine the memory allocated for the buffer. This option is given to you so you may decide to use different buffer size than the default 1024. lineRead() returns the newline terminated string in rl_line field of lineread structure. Return values of lineRead() are: 1 - RL_BUFSIZE - normal length of returned string. 0 - If zero is returned just after select(), end-of-file condition has occurred. Otherwise string is not completed yet. Make sure you call select() (or use non- blocking IO) if you don't want next call to block. -1 - if rl_Line field of lineread structure is NULL, it indicates error condition. If rl_Line points to start of string buffer, input string has been longer than buffer. In this case rl_Line points to zero terminated string of length RL_BUFSIZE. You may modify the zero terminated string returned by lineRead() in any way, but memory around the string is private lineread memory. EXAMPLE /* * The following code shows how to use lineread with select() */ #ifdef USE_LOW_MEMORY_BUFFER #define RL_BUFSIZE 256 #endif #include <sys/types.h> #ifdef AMIGA #include <bsdsocket.h> #endif #include <lineread.h> #define NULL 0 ... main_loop(int sock) { struct LineRead * rl; int length; fd_set reafdfs; if (rl = (struct LineRead *)AllocMem(sizeof (*rl), 0)) { initLineRead(rl, sock, LF_REQLF, RL_BUFSIZE); FD_ZERO(&readfds); while(1) { FD_SET(sock, &readfds); if (select(sock + 1, &readfds, NULL, NULL, NULL)) < 0) { perror("select"); break; } if (FD_ISSET(sock, &readfds)) if ((length = lineRead(rl)) == 0) /* EOF */ break; do { if (length > 0) write(1, rl->rl_Line, length); /* stdout. write() for */ /* speed demonstration */ else { /* length == -1 */ if (rl->rl_Line == NULL); { perror("lineRead"); break; } else { fprintf(stderr, "lineread input buffer overflow!\n"); write(1, rl->rl_Line, RL_BUFSIZE); write(1, "\n", 1); } } } while ((length = lineRead(rl)) != 0); /* 0 -> do select() */ } FreeMem(rl, sizeof (*rl); } else fprintf("AllocMem: Out Of memory\n"); } PORTABILITY The source modules lineread.c and lineread.h should compile in UNIX machines as is. AUTHORS Tomi Ollila, the AmiTCP/IP Group <amitcp-group@hut.fi>, SEE ALSO readChar(), bsdsocket.library/recv() netlib.doc/passwd netlib.doc/passwd NAME passwd - format of the password file DESCRIPTION The passwd files are files consisting of newline separated records, one per user, containing seven bar (`|') separated fields. These fields are as follows: name User's login name. password User's encrypted password. uid User's id. gid User's login group id. gecos General information about the user. home_dir User's home directory. shell User's login shell. The name field is the login used to access the computer account, and the uid field is the number associated with it. They should both be unique across the system (and often across a group of systems) since they control file access. While it is possible to have multiple entries with identical login names and/or identical user id's, it is usually a mistake to do so. Routines that manipulate these files will often return only one of the multiple entries, and that one by random selection. The login name must never begin with a hyphen (`-'); also, it is strongly suggested that neither upper-case characters or dots (`.') be part of the name, as this tends to confuse mailers. No field may contain a bar (`|') as this has been used to separate the fields in the user database. The password field is the encrypted form of the password. The format of the password field is still unclear, since the crypt() function is not implemented. If you have a suitable one ready, please contact authors <AmiTCP-Group@hut.fi>. Currently an asterisk `*' should be put into the password field. If the password field is empty, no password will be required to gain access to the machine. This is almost invariably a mistake. Because these files contain the encrypted user passwords, they should not be readable by anyone without appropriate privileges. The group field is the group that the user will be placed in upon login. The gecos field normally contains comma (`,') separated subfields as follows: name user's full name office user's office number wphone user's work phone number hphone user's home phone number This information is used by the finger program. The user's home directory is the full DOS path name where the user will be placed on login. The shell field is the command interpreter the user prefers. If there is nothing in the shell field, the CLI is assumed. FILES AmiTCP:db/passwd SEE ALSO netlib/getpwuid(), netlib/getpwnam() BUGS User information should (and eventually will) be stored elsewhere. The library functions getpw*() are the preferred way to access the user database. COPYRIGHT Copyright 1980, 1991 The Regents of the University of California. HISTORY A passwd file format appeared in Version 6 AT&T UNIX. The used format is basically the same as in the Multiuser Library 1.3 and AS225r2 use, except the password field. netlib.doc/timerinit netlib.doc/timerinit NAME timerinit - SAS C Autoinitialization Functions for timer.device SYNOPSIS _STIopenTimer() void _STIopenTimer(void) _STDcloseTimer() void _STDcloseTimer(void) FUNCTION These functions open and close the timer.device at the startup and exit of the program, respectively. For a program to use these functions, it must be linked with netlib:net.lib. The opened device base is stored in the TimerBase global variable. If the device can be opened, the _STIopenTimer() sets up the time zone information, which is used by the gettimeofday() function. NOTES The time zone information is got from the environment variable named TZ. The format for this variable is: zzznnnddd where zzz is three letter identifier for the time zone (for example GMT), and the nnn is hours west from Greenwich on range [-23,24] (negative values are to east). The last field is the abbreviation for the local daylight saving time zone (which is not interpreted by this version). If the TZ environment variable cannot be found, Greenwich Mean Time (GMT) is used instead. The autoinitialization and autotermination functions are features specific to the SAS C6. However, these functions can be used with other (ANSI) C compilers, too. Example follows: /* at start of main() */ atexit(_STDcloseTimer); _STDopenTimer(); BUGS TZ "hours west from GMT" should be interpreted as float. SEE ALSO netlib.doc/gettimeofday(), SAS/C 6 User's Guide p. 145 for details of autoinitialization and autotermination functions.